 (September 1999)(Disk 2).iso/Technical Publications/quicktime/qtdevdocs/images/qtsmban.gif){kind=small}
 (September 1999)(Disk 2).iso/Technical Publications/quicktime/qtdevdocs/images/qt4api.gif)
QuickTime 4 Reference
| Previous | Chapter Contents | Chapter Top | Next |
The TextExportGetDisplayData function retrieves text display information for the current sample in the specified text export component.
pascal ComponentResult TextExportGetDisplayData (
TextExportComponent ci,
TextDisplayData *textDisplay);You call this function to retrieve the text display data structure for a text sample. The text display data structure contains the formatting information for the text sample. When the text export component exports a text sample, it uses the information in this structure to generate the appropriate text descriptors for the sample. Likewise, when the text import component imports a text sample, it sets the appropriate fields in the text display data structure based on the sample's text descriptors.
The TextExportGetTimeFraction function retrieves the time scale the specified text export component uses to calculate time stamps.
pascal ComponentResult TextExportGetTimeFraction (
TextExportComponent ci,
long *movieTimeFraction);The TextExportSetTimeFraction function set the time scale the specified text export component uses to calculate time stamps.
pascal ComponentResult TextExportSetTimeFraction (
TextExportComponent ci,
long movieTimeFraction);You call this function to set the time scale used by the text export component to calculate the fractional part of time stamps. You can also set a text component's time scale by specifying it in the text export settings dialog box. You can retrieve a text component's time scale by calling the TextExportGetTimeFraction function.
The TextExportGetSettings function retrieves the value of the text export option for the specified text export component.
pascal ComponentResult TextExportGetSettings (
TextExportComponent ci,
long *setting);You call this function when exporting text to retrieve the current value of the text export option for the specified text export component. If the retrieved text export option is kMovieExportTextOnly , the text export component exports text without time descriptors or time stamps. If the retrieved text export option is either kMovieExportAbsoluteTime or kMovieExportRelativeTime , the text export component exports text along with its text descriptors and time stamps.
The TextExportSetSettings function sets the value of the text export option for the specified text export component.
pascal ComponentResult TextExportSetSettings (
TextExportComponent ci,
long setting);You call this function when exporting text to set the value of the text export option for the specified text export component. To export text only, without time descriptors or time stamps, you should set the setting parameter to kMovieExportTextOnly . To export text with text descriptors and absolute time stamps, you should set the setting parameter to kMovieExportAbsoluteTime . To export text with text descriptors and relative time stamps, you should set the setting parameter to kMovieExportRelativeTime .
The MovieImportGetFileType allows your movie data import component to tell the Movie Toolbox the appropriate file type for the most-recently imported movie file.
pascal ComponentResult MovieImportGetFileType (MovieImportComponent ci, OSType *fileType);The MovieImportGetAuxiliaryDataType function returns the type of the auxiliary data that it can accept. For example, calling the text import component with MovieImportGetAuxiliaryDataType indicates that the text import component will use 'styl' information in addition to 'TEXT' data.
pascal ComponentResult MovieImportGetAuxiliaryDataType(
MovieImportComponent ci,
OSType *auxType);Returns a list of MIME types supported by the movie import component.
pascal ComponentResult MovieImportGetMIMETypeList (
MovieImportComponent ci,
QTAtomContainer *mimeInfo);Your movie import component can support MIME types that correspond to formats it supports. To make a list of these MIME types available to applications or other software, it must implement the MovieImportGetMIMETypeList function.
To indicate that your movie import component supports this function, set the hasMovieImportMIMEList flag in the componentFlags field of the component description record.
If your component includes a private component resource holding this MIME data, it can use GetComponentResource to retrieve it. If the resource is a public component resource, it can use either GetComponentPublicResource with the public type and ID or GetComponentResource with the private type and ID.
The MovieImportValidate function allows your movie data import component to validate the data to be passed to your component. Its purpose is to indicate whether or not the file or data can be imported by the component.
pascal ComponentResult MovieImportValidate(
MovieImportComponent ci,
const FSSpec *theFile,
Handle theData,
Boolean *valid);The MovieImportValidateDataRef function lets your movie data import component validate the data file indicated by the data reference. This function allow the import to indicate if the file can be imported.
pascal ComponentResult MovieImportValidate( MovieImportComponent ci,
Handle dataRef,
OSType dataRefType,
Uint8 *valid);Movie import components can implement this function to allow applications to determine if a given file referenced by a data reference is acceptable for a particular import component. The data reference can refer to any data for which there is a suitable DataHandler component installed and available to QuickTime. As this function may be called on many files, the validation process should be as fast as possible. Furthermore, the importer should probably limit the amount of reading it performs, particularly when the data handler refers to data on the Internet.
Unlike MovieImportValidate , the valid parameter for this function is a value that can be interpreted as the degree to which the importer can interpret the file's contents. In all cases, returning 0 indicates the file cannot be interpreted by the importer. However, other nonzero values can be used to determine the relative weighting between multiple importers that can import a particular kind of file. For now, it is best to return either 0 or 128 only.
The MovieImportSetOffsetAndLimit function allows your application to specify the location and size of data that should be imported. Typically, this is used when the data is from a part of a file rather than the entire file.
pascal ComponentResult MovieImportSetOffsetAndLimit(
MovieImportComponent ci,
unsigned long offset,
unsigned long limit);The MovieImportSetOffsetAndLimit function is especially useful when one file format is embedded in another; it allows your application to skip header data for the enclosing file and begin importing data at the start of the desired format.
Not all movie import components support the MovieImportSetOffsetAndLimit function. Those that do include the movie import components for the kQTFileTypeAIFF , kQTFileTypeWave , and kQTFileMuLaw file types. Those that do not return the badComponentSelector result code in response to a MovieImportSetOffsetAndLimit call.
The MovieImportSetOffsetAndLimit64 function serves the same purpose as MovieImportSetOffsetAndLimit . The only difference is that the offset and limit can hold 64-bit offsets.
pascal ComponentResult MovieImportSetOffsetAndLimit(
MovieImportComponent ci,
wide * offset,
wide * limit);The MovieImportSetOffsetAndLimit function is especially useful when one file format is embedded in another; it allows your application to skip header data for the enclosing file and begin importing data at the start of the desired format.
Not all movie import components support the MovieImportSetOffsetAndLimit function. Those that do not return the badComponentSelector result code in response to a MovieImportSetOffsetAndLimit call. Also, if MovieImportSetOffsetAndLimit64 function is not implemented and the offset and limit can be expressed using 32 bit offsets, MovieImportSetOffsetAndLimit should be tried.
The MovieImportGetSettingsAsAtomContainer routine retrieves the current settings from the movie import component.
pascal ComponentResult MovieImportGetSettingsAsAtomContainer (
MovieImportComponent ci,
QTAtomContainer *settings);The MovieImportSetSettingsFromAtomContainer routine sets the movie import component's current configuration from the passed settings data.
pascal ComponentResult MovieImportSetSettingsFromAtomContainer (
MovieImportComponent ci,
QTAtomContainer settings);This section describes new functions provided by movie data export components.
Since QuickTime 1.6.1, the sound movie export component has been updated to take advantage of Macintosh Sound Manager 3.0. Previously, only the first sound track in the movie was exported. Now sound tracks are mixed together before they are exported. If you want to use sound mixing, you can use the PutMovieIntoTypedHandle function to take advantage of the export component. Furthermore, you can now specify the format of the exported sound, so you can convert 16-bit sound to 8-bit sound or reduce stereo to monaural. See Inside Macintosh: QuickTime for a description of the PutMovieIntoTypedHandle function.
QuickTime 1.6.1 added a new result code to this function. A movie export component returns the following result code when MovieExportGetAuxillaryData is called requesting a type of auxiliary data that the component cannot generate.
The MovieExportSetSampleDescription function allows your application to request the format of the exported data. This function is supported by the sound movie export component, for example. This function is not implemented by all movie export components.
pascal ComponentResult MovieExportSetSampleDescription(
MovieExportComponent ci,
SampleDescriptionHandle desc,
OSType mediaType);A movie export component may use all, some, or none of the settings from the sample description.
Some movie export components treat the sample description as part of their settings. If your application attempts to set the sample description using MovieExportSetSampleDescription, and receives the badComponentSelector error, you may need to pass in the sample description using the MovieExportSetSettingsFromAtomContainer function. You can use the MovieExportGetSettingsAsAtomContainer to obtain a correctly formatted atom container to modify.
The MovieExportValidate function allows your application to determine whether a movie export component can export all the data for a specified movie or track.
pascal ComponentResult MovieExportValidate(
MovieExportComponent ci,
Movie theMovie,
Track onlyThisTrack,
Boolean *valid);MovieExportValidate allows an application to determine if a particular movie or track could be exported by the specified movie data export component. The movie or track is passed in the theMovie and onlyThisTrack parameters as they are passed to MovieExportToFile .
Although a movie export component can export one or more media types, it may not be able to export all the kinds of data stored in those media. The MovieExportValidate function allows applications to get this additional information.
Movie data export components that implement this function also set the canMovieExportValidateMovie flag in their component flags.
This section describes new functions provided by movie data export components that allow applications to export data from sources other than movies.
The function allows you to define a data source for use with an export operation performed by MovieExportFromProceduresToDataRef .
pascal ComponentResult MovieExportAddDataSource (MovieExportComponent ci, OSType trackType,
TimeScale scale, long *trackID, MovieExportGetPropertyUPP
getPropertyProc, MovieExportGetDataUPP getDataProc, void *refCon);The MovieExportFromProceduresToDataRef function exports data provided by MovieExportAddDataSource to a location specified by dataRef and dataRefType .
pascal ComponentResult MovieExportFromProceduresToDataRef (MovieExportComponent ci, Handle
dataRef,
OSType dataRefType);The MovieExportSetGetMoviePropertyProc function is used to specifry the procedure that the export component should call to retrieve movie level properties during MovieExportFromProceduresToDataRef .
pascal ComponentResult MovieExportSetGetMoviePropertyProc (
MovieExportComponent ci,
MovieExportGetPropertyUPP getPropertyProc,
void * refCon);With QuickTime 4, applications can specify a MovieExportGetPropertyProc that will be called to retrieve movie level properties during the exporter's MovieExportFromProceduresToDataRef execution. This procedure is identical to a data source property procedure except that it is called for movie properties.
For example, the QuickTime movie export component may call the procedure with movieExportTimeScale to retrieve the time scale for the exported movie. If the property procedure is not specified or doesn't support this property, than the default movie time scale (600) is used.
MovieExportToDataRef allows an application to request that data be exported to a data reference, instead of to a file.
pascal ComponentResult MovieExportToDataRef(MovieExportComponent ci, Handle dataRef, OSType
dataRefType, Movie theMovie, Track onlyThisTrack, TimeValue startTime,
TimeValue duration);The MovieExportGetSettingsAsAtomContainer routine retrieves the current settings from the movie export component.
pascal ComponentResult MovieExportGetSettingsAsAtomContainer (
MovieExportComponent ci,
QTAtomContainer *settings);The caller is responsible for disposing of the returned QT atom container.
Applications programmers can call this function to obtain a correctly formatted atom container to use with MovieExportSetSettingsFromAtomContainer . This might be done after a call to MovieExportDoUserDialog , for example, to apply the user-obtained settings to a series of exports.
The MovieExportSetSettingsFromAtomContainer routine sets the movie export component's current configuration from the passed settings data.
pascal ComponentResult MovieExportSetSettingsFromAtomContainer (
MovieExportComponent ci,
QTAtomContainer settings);The settings QT atom container may contain atoms other than those expected by the particular component type or may be missing certain atoms. The MovieExportSetSettingsFromAtomContainer routine uses only those settings it understands.
Applications programmers should be aware that some movie export components treat sample descriptions as part of their settings. If your application attempts to set the sample description using MovieExportSetSampleDescription, and receives the badComponentSelector error, you may need to pass in the sample description using the MovieExportSetSettingsFromAtomContainer function. You can use the MovieExportGetSettingsAsAtomContainer to obtain a correctly formatted atom container that you can then modify.
This section documents routines provided by the QuickTime movie export component. These functions can be used by other data export components to implement their own functionality.
MovieExportNewGetDataAndPropertiesProcs returns MovieExportGetProperty and MovieExportGetData procedures that can be passed to MovieExportAddDataSource to create a new data source. This function exists in order to provide a standard way of getting data using this protocol out of a movie or track.
pascal ComponentResult MovieExportNewGetDataAndPropertiesProcs (MovieExportComponent ci,
OSType trackType, TimeScale *scale, Movie theMovie, Track theTrack,
TimeValue startTime, TimeValue duration, MovieExportGetPropertyUPP
*getPropertyProc, MovieExportGetDataUPP *getDataProc, void **refCon);Disposes of the memory associated with the procedures returned by MovieExportNewGetDataAndPropertiesProcs.
pascal ComponentResult MovieExportDisposeGetDataAndPropertiesProcs (MovieExportComponent ci,
MovieExportGetPropertyUPP getPropertyProc, MovieExportGetDataUPP
getDataProc, void *refCon);The MovieExportGetPropertyProcPtr and MovieExportGetDataProcPtr routines are closely associated with MovieExportFromProcedures .
You use MovieExportGetPropertyProcPtr to return parameters that determine the appropriate format for the output data.
typedef pascal OSErr (*MovieExportGetPropertyProcPtr)(void *refcon,
long trackID, OSType propertyType,
void *propertyValue);The function defined by MovieExportGetPropertyProcPtr type is passed to MovieExportAddDataSource to define a new data source for an export operation. For example, a video export operation may call the function to determine the dimensions of the destination video track.
If the function doesn't have a setting for a requested property, it should return an error. The export component provides a default value for the property based on the source data format. For example, if no values for video track width and height properties were provided by the callback function, the dimensions of the source data would be used.
You use the function defined by MovieExportGetDataProcPtr to define a data source for an export operation.
typedef pascal OSErr (*MovieExportGetDataProcPtr)(void *refCon, MovieExportGetDataParams
*params);The sample request is made through a parameter block. The data structure used is shown below.
struct MovieExportGetDataParams {
long recordSize;
long trackID;
TimeScale sourceTimeScale;
TimeValue requestedTime;
TimeValue actualTime;
Ptr dataPtr;
long dataSize;
SampleDescriptionHandle desc;
OSType descType;
long descSeed;
long requestedSampleCount;
long actualSampleCount;
TimeValue durationPerSample;
long sampleFlags;
};
typedef struct MovieExportGetDataParams MovieExportGetDataParams;The function defined by the MovieExportGetDataProcPtr type is passed to MovieExportAddDataSource to define a new data source for an export operation. The function is used by the exporting application to request source media data to be used in the export operation. For example, in a video export operation, frames of video data (either compressed or uncompressed) are provided. In a sound export operation, buffers of audio (either compressed or uncompressed) are provided.
The data pointed to by dataPtr must remain valid until the next call to this MovieExportGetDataProcPtr function. The MovieExportGetDataProcPtr function is responsible for allocating and disposing of the memory associated with this data pointer.
Movie Data Exchange Component Resources
With QuickTime 4, data exchange components of both types declare public component resources that are useful to applications and QuickTime. Because these are public component resources, a number of benefits arise. First, clients can access the data without having to open the components which would require the code to be loaded and called. Second, since the resources have well known types and ids it is not necessary to define new component functions on the components just to retrieve the data. In some cases, older component routines may not need to be called if the data exchange component has a public component resource of the appropriate type. Finally, since component resources are cached, subsequent access to the data will typically be quite fast.
| Previous | Chapter Contents | Chapter Top | Next |